[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
twRABrowse( wT, wL, wB, wR, aArray, aColumns, cTitle,;
lEditFlag, aActionKeys, wColor,;
wSType, wFType, wFColor, lScBar, lAlite,;
nFreeze, lStabilize, bPreRun, bPostRun,;
nExitKey, lBarOn, aSeparators,;
aAppend, lSound, lWindow )
----------------------------------------------------------------------------
twRABrowse() is a powerful function allowing the programmer
practically unlimited choice in defining its mode of operation. It
arose out of the need for an all-purpose array browser for
construction of various order entry and invoicing systems.
There is built in mouse support, and the ability to pass
executable code to the function through the use of actionkeys. You
may also obtain a reference to the browse and its full cargo
structure, and modify its behaviour on the fly.
The default keystroke handling in twRABrowse() can be overridden by
assigning ActionKey blocks to replace the defaults. ActionKeys are
processed BEFORE the default keystroke handler. This method was
deemed easier for programmers than the method of passing an entire
ApplyKey function. Both methods will be made available in a
future release. The defaults vary according to the Autolite
setting:
Keystroke Handling:
Up Arrow ---------+
Down Arrow |
Left Arrow |
Right Arrow |
Page Down |- Scroll the Highlight Bar in
Page Up | the normal way.
Ctrl Page Down |
Ctrl Page Up |
Ctrl Left Arrow |
Ctrl Right Arrow |
Ctrl Home |
Ctrl End ---------+
Escape - Exit with no choice.
Enter - If EditFlag is .T., allow editing of
the current element in the current
array, otherwise, exit the browse.
F1 - Display default keystroke handling.
F8 - Swap current column with the one on
the left.
F7 - Delete the current column from the
display.
F9 - Subtract one to the count of columns
on the left which are frozen. The
freeze value defaults to 0.
F10 - Add one to the count of columns
on the left which are frozen. The
freeze value defaults to 0.
If lAlite is False, the right and left arrow keys pan the
browse. If it is true, the cursor is moved one column.
The built in Get System allows the user to perform gets on the
entire browse or only on selected columns. The ability to define a
reader makes the browse totally configurable to your needs.
An append mode is included, but editing and appending to databases
is best performed by executing the task through ActionKeys. The
ability to edit and append in an array browser allow you to, for
instance, create invoices without reference to a database and
throw them away if they are not used. Naturally, inventory
management must still be done. Ahhrghh!
Both vertical and horizontal scrollbars are available. If you
allow scrollbars, the horizontal one is displayed only if the
entire browse will not fit within the window.
Mouse Support:
The default mouse support varies according to the value of
lEditFlag.
When the browse is internally configured, two mouse hot spots may
be defined. The hot spots will cover the area occupied by the
scrollbars. If scrollbars are allowed, the mouse actions are:
Vertical Scroll Bar:
Direction Arrows:
Left Button: Up or Down one line.
Right Button: Page Up or Down.
Both Buttons: Top or Bottom of array.
Shaded Area: Move to Relative array Position.
Horizontal Scroll Bar: Left Button
Shaded Area: Move to Relative Column Position.
lEditFlag is TRUE:
Direction Arrows: Right or Left One Column.
lEditFlag is FALSE:
Direction Arrows: Pan Right or Left.
Browse Table:
Right Button: Escape with no choice.
Left Button:
lEditFlag is TRUE:
Single Click: Move to element.
Double Click: Edit element.
lEditFlag is FALSE:
Single Click: Move to element.
Double Click: Select element and
EXIT.
You may add your own mouse actions to the browse with
twRAHotSpot().
Arguments:
aArray - 'A' The array to browse: single or multi dimensional.
aColumns - 'A' An array of column definitions to browse.
Each element in the column array passed to
twRABrowse() MUST have at least TWO elements.
One is for the column header and the other for
the block used to display the data. Six other
elements are possible, but are not necessary.
One is the column width and the others define
and modify the get system in the browse.
The following is the array structure used to
pass columns to the browse:
Column Structure to Pass in aColumns:
AADD( aColumns, { cHead, nClm, nWid, cFoot, ;
lEdit, cPic, bWhn, bVld, ;
bRdr, aClr, bClr, cCsep, ;
cHsep, cFsep })
Where:
1 - cHead - Browse Column Header
2 - nClm - Browse Array Column for
Multi Dimensional Arrays
3 - nWid - Optional Column Width
4 - cFoot - Browse Column Footer
5 - lEdit - Optional Logical to Allow Edits
6 - cPic - Optional Picture for Gets
7 - bWhn - Optional When Block for Gets
8 - bVld - Optional Valid Block for Gets
9 - bRdr - Optional Reader Block for Gets
10 - aClr - Browse Column DeFColor
11 - bClr - Browse Column Colorblock
12 - cCsep - Browse Column Separator to left
13 - cHsep - Browse Column Head Separator
14 - cFsep - Browse Column Foot Separator
NOTE: For arrays of single dimension, nClm
becomes zero automatically. For Multi-
Dimensional arrays, nClm is found from the
structure:
aArray := { "xxxxx", "xxxxx", "xxxxx",... }
nClm := 1 2 3 etc.
The Get Reader may be configured to allow cursor
movements after editing columns or to keep the
cursor out of columns. twRABrowse() can therefore
be configured to behave as a spreadsheet by
adding suitable auxiliary functions.
NOTE: The get system will operate only if the
lEditFlag is set to true in the function call. If
it is, individual columns may be excluded from
editing by setting the fourth element, lEdit in
the column definition to False.
NOTE: If you use the append mode, all False
column definitions of lEdit become True.
Therefore, if appends are allowed, pictures,
whens, valids and readers may have to be assigned
to columns which are normally NOT editable. They
will be editable during appends.
It is recommended that the edit, and especially
the append mode be reserved for 'down and dirty'
situations. The use of ActionKeys will allow you
to process database edits and appends much more
satisfactorily. However, when appending or
deleting from arrays, other concerns must be
taken into account. The internals of twRABrowse()
depend on an up to date knowledge of the length
of the array and the current element. There are
associated functions to allow you to perform
these additional housekeeping chores:
twRAGetBrowse()
twRAGetElement()
twRAGetCurrent()
twRAGetArray()
twRASetArray()
cTitle - 'C' Optional Title for the browse. See also bPreRun.
lEditFlag - 'L' Logical to allow editing of fields. If you are
working in a network environment it is best to
edit records through the use of ActionKey
procedures, but you may include your network
file or record locking functions in the
individual column definitions or by replacing
the default keystroke handling where necessary
by passing ActionKeys to override the defaults.
The default is .F.
aActionKeys - 'A' An array of keys and code blocks to be executed
during the browse.
ActionKeys provide a means to pass executable
code to a browse. The information is passed in
an array where each element is a two element
array:
AADD( aActionKeys, { nKey, bBlock } )
Where: nKey - key number to assign
bBlock - code block to execute
If you are using SET Keys, you should save any
of them which might conflict with your
actionkeys before calling the browse, then
restore them on return.
wColor - 'C' Clipper colour string with which to configure
the browse. In order to be consistent with other
functions in TSDWIN, wColor must be passed as a
Clipper colour string. The minimum acceptable is
NIL, in which case the colour defaults to the
current SETCOLOR(). You must ensure that
SETCOLOR() is a full length colour string if you
do this.
The basic format for passing a colour is:
"x,x,,x,x"
TSDWIN uses the first two elements in the list
as the standard and enhanced colours for the
browse, and ALWAYS the last one for the
unselected colour, no matter how long your
colour string is. In a future release of TSDWIN,
all colours will be passed to all functions as
colorspecs.
You may want to pass more complicated colorspecs
if you choose to enhance your browse through the
column definitions.
wSType - 'N' TSDWIN Shadow type. The default is 0.
wFType - 'N' TSDWIN Frame type. The default is 1.
wFColor - 'C or A' If a character value is passed, it becomes
the frame colour for active and inactive
windows. If an array is passed, the first
element is used for active windows and the
second for inactive. If you are opening
other windows through ActionKeys, it is
recommended you use an array for this
parameter. wFColor defaults to the current
window colour.
lScBar - 'L' Logical for Scroll bar display. If this is set
to .T., a vertical bar is always displayed but a
horizontal bar is displayed only when the
columns in the browse will not fit into the
window. The default is .F.
lAlite - 'L' Logical to allow individual field highlighting.
If .T. the normal Clipper field highlighting is
followed. If .F., the highlight bar extends
across the entire window, including the column
separators. The default is .F., ie., NO field
highlighting.
nFreeze - 'N' The initial number of columns to freeze. The
default is 0.
lStabilize - 'L' The TBrowse Stabilize() method allows users to
break out of the stabilization process if a key
is pressed, thereby allowing the user faster
response on key presses. However, not all users
like the results when this is allowed. The
display will go blank in the browse window as
long as the user holds down a navigation key for
up or down movement. The lStabilize parameter
indicates whether or not carry out stabilization
to completion before processing the next key
press. The default is .F., indicating NOT TO
FINISH STABILIZING the browse as keys are
pressed. For large databases, the difference in
speed is very noticeable. The default is .F.
bPreRun - 'B' You may pass in a code block to execute before
the browse begins. For instance, the default
title colour in the browse is the standard text
colour. bPreRun allows you to change this by
leaving cTitle as NIL and creating:
bPreRun := {|| twTitle( "Title", YourColor" )}
bPostRun - 'B' This parameter acts like the PreRun block but is
executed after leaving the browse before the
browse window is popped if there is one.
nExitKey - 'N' The default exit keys are ESC and ENTER ( if
editing is disallowed ). You may wish to change
the behaviour of a browse with an ActionKey,
Therefore provision is made here to allow a
different key to provide an escape sequence.
Many users choose K_ALT_X to exit as it is used
in most CUA systems.
lBarOn - 'L' lBarOn defaults to .T. and indicates whether or
not the highlight bar is to be displayed when
AutoLite is set to off. If you set it to .F.,
you can use this browse to scan text files which
you have stored in an array.
aSeparators - 'A' An optional three element array of browse
separators. If this parameter is passed, it must
take the form:
{ HeadSep, ColSep, FootSep }
Column definitions may be used to override this
parameter.
aAppend - 'A/C' If you wish to allow appends to the array
being browsed, you must pass an empty element
with which to do the append. In th case of a
one dimensional array, the element will be a
string. For multi-dimensional arrays, it will
be one element.
lSound - 'L' Logical to allow a tone at HitBottom and HitTop.
lWindow - 'L' lWindow indicates whether you want the function
to open a window in which to display the browse.
You may wish to create a browse in part of a
window. lWindow allows you to do this. If
lWindow is set to .F., no window is displayed
and the browse fills the entire coordinate area.
Return:
Selected array element or zero for no selection. If you require a
different return, use twRAGetArray() with bPostRun.
Example:
This example is taken from an actual application.
FUNCTION ShowEdit( aShowCol, aGetSpots, aShowSpots )
LOCAL f, bK_F2 := SETKEY( K_F2, NIL ), g
LOCAL bK_F3 := SETKEY( K_F3, NIL )
LOCAL bK_F10 := SETKEY( K_F10, NIL )
LOCAL aActionKeys := {}
aShowSpots := {}
// Disable the hot spots from the caller.
FOR F = 1 TO LEN( aGetSpots )
twRESpotOff( aGetSpots[ F ] )
NEXT
IF twOKMouse()
// hide the mouse
// TSDWIN functions with mouse support
// assume the mouse is off on entry
_twM2()
ENDIF
// add the hot spots
AADD( aShowSpots, twRAHotSpot( 24, 00, 24, 24,;
{|| ShowSelect( aShowSpots ), ;
twRABarDisp() }, 1,, .T. ))
AADD( aShowSpots, twRAHotSpot( 24, 28, 24, 43, ;
{|| RowDel( 1 ) }, 1,, .T. ))
AADD( aShowSpots, twRAHotSpot( 24, 46, 24, 67, ;
{|| __keyboard( CHR( K_ENTER )) }, 1,, .T. ))
AADD( aShowSpots, twRAHotSpot( 24, 70, 24, 77, ;
{|| __keyboard( CHR( K_ESC )) }, 1,, .T. ))
// add the actionkeys
AADD( aActionKeys, { K_F10, {|| ShowSelect( aShowSpots ),;
twRABarDisp() } })
AADD( aActionKeys, { K_DEL, {|| RowDel( 1 ) }})
// add actionkeys to stop cursor right
AADD( aActionKeys, { K_RIGHT, {|| NIL }})
AADD( aActionKeys, { K_CTRL_RIGHT, {|| NIL }})
AADD( aActionKeys, { K_END, {|| NIL }})
// display selection list and hot spots
twInfoLine( -2, ".F10..List and Select Shows " +;
.DEL.. Delete Show " +;
.ENTER/ALPHA..Enter Show .ESC..Done", "P" )
// browse the array. Appends allowed.
twRABrowse( 11, 0, 23, 40, aShow, aShowCol,, ;
.T., aActionKeys, MCOLORN, 0, YFRAME, ;
MCOLORFN, .T., .T., 2, .T. ;
,,,,, { "---", " | ", "" }, ;
{ " ", SPACE( 30 ) } )
twAMPop()
// release hot spot handles
FOR F = 1 TO LEN( aShowSpots )
twRARemHotSpot( aShowSpots[ F ] )
NEXT
ASORT( aShow,,, {|x,y| x[ 1 ] < y[ 1 ] } )
FOR F = 1 TO LEN( aShow )
@ 13 + F, 2 SAY aShow[ f, 1 ] + ;
" | " + aShow[ f, 2 ]
IF f = 9
EXIT
ENDIF
NEXT
IF f < 9
FOR g = f to 9
@ 13 + g, 2 SAY SPACE( 5 ) + "|" + SPACE( 30 )
NEXT
ENDIF
SETKEY( K_F10, bK_F10 )
SETKEY( K_F3, bK_F3 )
SETKEY( K_F2, bK_F2 )
IF twOKMouse()
// show the mouse
_twM1()
ENDIF
// Enable the hot spots
FOR F = 1 TO LEN( aGetSpots )
twRESpotOn( aGetSpots[ F ] )
NEXT
RETURN NIL
See Also:
twABBrowse()
twACChoice()
twRAHotSpot()
twRAMouseLine()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson